MultiXTpm gSoap Enhancer - MSE

Open Source/Free Software

MultiXTpm gSoap Enhancer is an application built on top MultiXTpm Application Server. Its purpose is to assist gSoap developers in implementing a large, scalable, load balanced system with as little effort as developing only the service routines. It frees the developer from all concerns relating to communications and transport issues, threads, processes and sessions management.

As a MultiXTpm based application, MSE enhances gSoap by providing the following features without any programming effort required from the developer:

Develop only the service functions in a single DLL. This eliminates the need for developing a complete program with listeners and threads. This also eliminates the need to develop multiple web services in a single process or the need to handle multiple DLLs in a single process.
Session management. This enables the service functions maintain states between invocations of the same function or even between different functions in the same web service and even between different functions in different web services.
Route web service calls to different processes and DLLS based on the URL specified in the request. In addition, if SOAPAction is specified, the call can be configured to be routed to a specific function in a specific DLL.
Complete separation between the Listener/Transport handler and the Web Service functions that implement the business logic. This means that the Listener/Transport handler can be located on one machine and the Web Service function can be executed on another machine.
Configuration dependent SSL support at the Front End Process. No recompilation of gSoap code required in order to switch between SSL and non-SSL modes.
Configuration Dependent HTTP Basic Authentication at the Front End Process. Enables a single point of Authentication and Authorization, regardless of the number of Web Services supported and without the need to include Authentication and Authorization at the web service code.
The separation between the Listeners and the Back End processes that handle the business logic enables configuring the system to support any desirable combination of Listeners/Ports/Back End processes. The following table shows all available combinations.

Listeners	Ports	Back End Processes	Web Services	Comment
Single	Single	Single	Single	This is how its done when using gSoap AS IS in a single process
Single	Single	Single	Multiple	Seamlessly adds the ability to support more then one Web Service in a Single Process
Single	Single	Multiple	Single	Seamlessly adds the ability to handle a Single Web Service in more than one process and maybe on more than one machine. This adds scalability and better availability. MultiXTpm Load Balances between all process instances.
Single	Single	Multiple	Multiple	Seamlessly adds the ability to handle Multiple Web Services in an array of processes located on one or more machines. In addition to the benefits mentioned above, this can also reduce the number of processes when large number of Web Services is required.
Single	Multiple	Single or Multiple	Single or Multiple	In addition to all benefits mentioned above, this adds the ability to provide services on multiple ports without hooking a single Web Service to a Single Port.
Multiple	Single or Multiple	Single or Multiple	Single or Multiple	In addition to all benefits mentioned above, this adds the ability to provide services using more then one Listener process and on more than one machine.

MSE is an application layer router. In general this means that it is a standard application running on a host, anticipating all incoming traffic on predefined ports, and after parsing the received data for some information, it routes the entire message to a predefined set of applications/processes based on some data found in the header of the incoming message. After the target application has processed the data and replied with some other data, MSE routes back the response to the sender of the request.

MSE, as an application layer router, supports the HTTP/SOAP as the application layer protocol. This means that when MSE is started, it starts listening on one or more preconfigured ports for incoming HTTP requests. Once a connection is established, MSE waits for the entire HTTP header to arrive. Based on the header that was received, MSE extracts 3 pieces of information:

The internal path to the web service name.
The SOAPAction – if it exists.
The entire message length.

Once this information is extracted, MSE waits for the entire message to arrive. Once it has all the data, MSE forwards the entire message to one or more processes based preconfigured rules for the routing. When response(s) from application(s) arrive, MSE chooses the most appropriate response (will be discussed later) and it forwards it back to the sender. In order to handle all HTTP/SOAP parsing and services invocations, MSE uses the gSoap toolkit. This means MSE will integrate seamlessly into environments that use gSoap as their platform for handling Web Services Requests, provided that the web services are compiled as DLLs and not as EXECUTABLES. For all other cases, MSE handles all TCP/IP interface and all routing/load balancing, but the final applications, will have to handle the Web Service invocation, handing over the data forwarded by MSE, and handing over to MSE the response from the Web Service function.

Architecture

MSE runtime environment comprises of 3 processes at the minimum:

MultiXTpm – Application Server, Router, load balancer.
MultiXWSFE – Front End process.
MultiXWSServer – Web services dispatcher.

MultiXWSFE

This process acts as a Listener/Transport handler. It is responsible for the actual communication with HTTP/SOAP client. When a new connection is established, it creates a new session object, it waits for incoming HTTP/SOAP messages and when a full message is received, it is forwarded to MultiXTpm process (in the context of the session created earlier) with a special indication of the SOAPAction and the internal logical path of the Web Service application. MultiXTpm in turn forwards the request to the appropriate process for the actual processing of the request. When a response comes from the Web Service application, it is forwarded back to the client. The connection is kept open, waiting for the next request, or disconnect from the client or an idle timer expires in which case the connection is aborted. This process is multithreaded and all communication activities are in NOWAIT manner, so it does not block on any call, so it can theoretically process unlimited number of connections simultaneously. This process can have more then one instance where each instance can manage a different range of ports. All instances can run on a single machine or can be divided between multiple machines.
Since MultiXWSFEhandles all communications with Web Services Clients, it provides two security related features to the system. SSL Support and HTTP Basic Authentication.

SSL Support
SSL Support is provided by MultiXTpm thru configuration of the Link objects. Since all connectivity to the Clients is done thru MultiXWSFE Links, this means that SSL related issues start and end in MultiXWSFE. When a new SSL connection is established with the Client, MultiXWSFE handles all the handshake and certificates exchange if required and moves on to the data transfer phase. When requests are forwarded from MultiXWSFE to MultiXTpm, they are forwarded as clear text, after being decoded by MultiXWSFE. When the requests propagate to the gSoap Web Service DLL, they get there in clear text, which means that no SSL support is required by the gSoap compiled units. A Developer should compile all source code without the "WITH_OPENSSL" define, the decision whether to use SSL or not is done thru configuration at runtime and not at compile time. Even more, the implementer may decide to require SSL per a group of web services, per specific web service DLL and if configured correctly, on function by function basis within a Web Service DLL. The most evident implication of this architecture is the ability to separate the Front End Process from the gSoap DLLs and put these processes on different machines, so SSL processing does not consume resources meant to be used by the applications themselves. To get more information on how to use SSL in MultiXTpm environment, please look at SSL_Support.htm located at MultiXTpm Application Server directory.

HTTP Basic Authentication
When MultiXWSFE receives the full SOAP message from the Web Service Client, it enables the application level code to check for user name and password, and if required, the application level code can request MultiX API to challenge the Client to send the user name and password. If a developer wishes to implement Authentication and Authorization in one centralized place, rather than in each Web Service DLL, Modifying the MultiXWSFE code is the best way to do it. Just go to the source file "MultiXWSFEServerLink.cpp" locate the function "CMultiXWSFEServerLink::IsAuthenticated()" and modify it to support whatever authentication and authorization mechanisms you choose.

MultiXTpm

This is the main process within this architecture. When it starts, it reads a preconfigured XML file where all configuration data is stored in. Among other things, it starts the first instances of the other processes. When the other processes are started, it provides them with some configuration data, specifically, it provides MultiXWSFE the information about the TCP/IP ports to listen on for incoming HTTP/SOAP requests. MultiXTpm's main responsibilities are:

Monitor the other processes for unexpected termination. When it realizes that one of the processes has terminated, it restarts it if it is configured to do so.
When a new request arrives from MultiXWSFE, it routes the request to one or more processes for handling the request.
Monitor the queues for the Web Services Applications. Based on configuration data, MultiXTpm maintains a queue for each Web Service Application process
Receiving a response from Web Service Application processes and forward the responses back to MultiXWSFE.

When forwarding a request to a Web Services Application process, MultiXTpm accompanies the raw data with information regarding the DLL to use and which function to call for the specific request. The DLL and function to call are configured separately from web service URL and the SOAPAction.

MultiXWSServer

This process is actually the Web Services Application. It's main function is to receive requests from MultiXTpm or from MultiXWSFE directly, load the appropriate user specified DLL and call the user specified function for that specific call. This process can have one or more instances running at the same time and it can run on a single or multiple machines. The number and the location of the processes is determined by MultiXTpm based on predefined configuration.

Figure 1 above illustrates the structure of MultiXTpm gSoap Enhancer and the data flow. Each web service call passes thru few phases starting from connection establishment and ending with the connection closing. Between these two phases the Client is said to be "in a session". Following is a brief description of the various phases.

The client sends its HTTP request.
MultiXWSFE Processes the HTTP header and receives the entire message.
The message is forwarded in its entirety with additional information regarding the Web Service URL and the SOAPAction if exists. If the request is the first one in the session, it is forwarded to MultiXTpm, otherwise it is forwarded directly to the MultiXWSServer (3S) that was previously elected by MultiXTpm on the first call.
MultiXTpm, upon receiving the new request, searches its local configuration data for an entry matching the URL and the SOAPAction, it does not scan the message AT ALL. If it finds such an entry, it elects the appropriate MultiXWSServer process and queues the message for a later forwarding to that processes. The new message includes the original data plus two preconfigured fields: the DLL to load and the Function to call.
If the queue for that process is empty or its size is below a preconfigured maximum, the message is forwarded immediately to the process.
Upon receiving the request, MultiXWSServer tries to load the DLL specified by MultiXTpm, if it does not find it or the function is not found in the DLL, an error reply is sent, otherwise, the function is called.
While the Web Service function is executing, no other Web Service call can be processed by this instance of MultiXWSServer, concurrency is achieved by using multiple processes in a distributed environment.
When the Web Service function returns, MultiXWSServer packs the response and forwards it back to the process it received the request from. See (3) (3S). If the request was received directly from MultiXWSFE, the response is sent directly to it (8S).
When MultiXTpm receives the response, it checks it's configuration to see if that response should be ignored, if not so, it forwards it to the sender of the request. Once a response is sent to the sender, all future responses for that request (in case of multiple recipients) are ignored.
The response is forwarded back to the MultiXWSFE process who originally received it from the client.
When the response from MultiXTpm or MultiXWSServer is received, MultiXWSFE checks that the connection with the client is still valid and if so, it forwards the response.
The response is sent to the Web Service client. At that point the client may elect to close the connection and as a result, MultiXWSFE will delete the session object. If the connection is not closed, MultiXWSFE will use the same session object for handling future requests.

gSoap sample DLLs

MSE includes 3 smaples to show how to to compile and use gSoap modules.

gSoapCalculator - This is a simple DLL with the basic operation.
gSoapDimeServer - This DLL is based on the "dimeserver" sample that is included with the gSoap distribution. The only difference is that it is compiled as a DLL and not as an executable.
gSoapEchoServer and gSoapEchoClient - An executable and a Server DLL that demonstrate a simple use of gSoap and MultiXTpm.

One important thin to notice in these examples is that all code to handle sockets and threads is totaly eliminated.

HTTP/SOAP Requests Handling

As mentioned before, MSE uses gSoap toolkit for parsing the SOAP header in MultiXWSFE and it assumes gSoap based DLLs when calling the Web Service functions. This means that the DLLs provided by the developer should be based on gSoap and that all gSoap code should be included in the DLL. MultiXWSServer uses some gSoap functions to initialize the "soap" structure and it assumes that the DLLs provided include these functions. The reason it is done this way, to avoid problems that could arise by using different versions of gSoap. It is advisable to compile the DLLs using the same gSoap version that is used when compiling MultiXWSFE and MultiXWSServer.

Download information

MultiXTpm Application Server is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

MultiXTpm Application Server is distributed in source code format and it supports: Windows OS, Linux, Solaris and HP Nonstop Server OSS.

The source code is packed in ZIP file and can be downloaded from SourceForge.net.

To Access the Download Page at SourceForge.net you may click Here
or
Navigate to http://sourceforge.net/projects/multixtpm

Contact information

For more information, Bug Reports, Feature Requests, and Support Requests, please use:
SourceForge.net tracker
or
SourceForge.net Project Forums
or
MultiXTpm group at Yahoo Groups.
or
you may send an email to: Moshe Shitrit

Home